The terms "character" and "save game data" are used interchangeably in the documentation, although character is usually used for a compound file (a file which, when opened in ACE, displays more than one window).
All information provided on resource editing assumes that you are using ResEdit.
Overview
The essential information on making a module is contained in the three development documents (part I, II and II). The development documents describing scripting, tabs and lists are optional.
Developer Information
The following information is important to the development and distribution of ACE! modules. If you disagree with these conditions, you cannot make or distribute new or modified versions of ACE! modules.
These conditions are necessary, in part, because the information that the ACE! module uses is not the property of the module author, nor of the author of the ACE! application.
1. You cannot charge money or any monetary equivalent for ACE! modules. That is, they must be freely distributed. If a module is included as part of a game package, it must be clear that any registration fee does not apply to the use of the ACE! module.
2. If you make a new ACE! module by adapting or expanding a module written by someone else, you must give them credit as the original author in the Module Info dialog, and retain the text of any module documentation provided by the original author in an unmodified state. It is acceptable to append your documentation to the original authors documentation file. Do not distribute modified modules if the only changes made are cosmetic, or are very minor.
3. Likewise, by making an ACE module, you agree that other people have the right to make and distribute modified versions of your module, as in clause 2 above.
4. The author of the ACE! application assumes no responsibility for modules created by anyone other than himself (see also the 'Legal' documentation). Authors of ACE! modules should give their own contact information.
Utilities
You will find the following applications useful if you choose to make your own modules for ACE. All version numbers are current at time of writing.
Name: ResEdit (Apple's resource editor)
Version: 2.1.3, available from Apple's web site.
Use ResEdit to make new modules, and to view and edit the resource fork of save games.
Other: Resourcer (1.2.8 and 2.2), Resurection <http://www.weblayout.com/witness/Resurrection.shtml>
Name: SuperHex (Data/resource fork editor by Yacine Ikhlef)
Version: 1.0b8, available from <http://perso.wanadoo.fr/yi/>
HexEdit can be used to view the data and resource fork of save files.
Other: Norton Disk Editor (part of the Norton Utilities), HexEdit by Lane Roathe (1.2.2) <ftp://ftp.ifd.com/pub/mac/HexEditApp.sit>
Name: ResCompare (Resource fork comparison utility, by Michael Hecht)
Version: 2.6, available from an Info-Mac mirror
ResCompare will note the differences between the data and resource forks of two or more files. You may not need this if you use HexEdit 1.2 or higher.
Name: Script Editor (Apple's OSA script editor)
Version: Any
The Script Editor allows you to write and record scripts (including AppleScripts). A copy is included on all MacOS CD's, and is installed as part of the default installation.
Name: Text to STR# (converts text to the 'STR#' resource format, by Richard Drysdall)
Version: 1.1, available from an Info-Mac mirror
This script-application converts a text file to the format used in the 'STR#' resource. It is useful when you need to enter a lot of information for a list.
Compatibility
The ACE! application uses the name of the module that appears in the Module menu (which is determined by the module filename) to differentiate between modules. If two modules have the same name, the behavior of the application will be unpredictable and corruption of save games may occur. To avoid this, all Modules must have different names. The author proposes that all modules distributed separately from the standard package should be followed by the name or nickname of the author.
Example: "Realmz (Gary)", "Marathon ∞ (Bob)" etc.
Likewise, uploads to online archives should be named in a similar fashion, but the filename should begin with the word 'ACE', to ensure that all ACE modules are grouped together alphabetically.
In the upload abstract, you should mention that the file belongs in the "Games Utilities" section (or equivalent). Note that the Info-Mac archives do not have a "Games Utilities" subdirectory, so you should request that the file be placed in the "Games" folder.
This will allow ACE! modules to be easily located by users, and should make life easier for archive maintainers.
Module Development
The basic steps to create a module are as follows
• Determine the offsets in the save file of the variables you want to edit.
• Create a module file and fill out all the necessary resources.
• Test the module file.
Open the save game with ResEdit. Choose the Get Info command from the File menu. In the Info dialog, note the numbers of bytes in the resource fork and the data fork:
• If there are zero bytes in the resource fork, the save game data is in the data fork, and you will need a data fork editor.
• If there are zero bytes in the data fork, the save game data is in the resource fork, and you will need a resource fork editor.
• If neither fork is zero bytes, then the save game data could be in either fork. You will need a data fork editor and a resource fork editor.
There are three methods you can use to decode the save game. All help you determine which offsets in the save game are associated with which game variables.
• The first method, save game comparison, only works well with games that are time independent. For example, games like Marathon and Doom are time dependant (even when you are doing nothing, monsters are moving, doors closing etc) and thus the save games cannot be easily decoded by save game comparison. You can test to see if a game is time dependant as follows:
1. Open the game.
2. Save.
3. Do nothing except wait for a few seconds.
4. Save again under a new name.
5. Quit the game
6. Compare the two save game files - if they are the same, the game is time independent. If they are different, the game is time dependant.
You can still proceed with this method if the game is time dependant, but you will need to determine which offsets in the save game file are changing with time, and exclude them in the next step.
The save game comparison is done as follows:
1. Open the game.
2. Save (this save game is now the original ).
3. Change one variable of the game - this may be moving a square, firing a shot etc - the important thing is that you should change only one variable. This is not as easy as it may sound. For example, dropping an item may remove the item from the character's inventory and place it on the map where it was dropped - at least two variables have changed.
4. Save again under a new name (this is the copy ).
5. Compare the two save game files. With luck, they will only differ by a few bytes. If not, try changing some other game variable. The offset of the changed bytes is where the save game data for that variable is stored.
6. Note the offset and the variable you changed.
7. Delete the save game copy, open the original save game, and go back to step 3.
• A second method is to make use of a save game editor someone else has written (this is obviously a bit cheeky). To determine if the save game editor is suitable:
1. Open the game.
2. Save (this save game is now the original ).
3. Quit the game.
4. Make a duplicate of the save game (this is now the copy ).
5. Open the save game copy with the save game editor.
6. Save (don't make any changes).
7. Compare the original and the copy of the save game. If they are the same, throw away the copy. If they are different, then the save game editor is either written for a different version of the game, or it is making some invalid assumptions. Try using the save game copy in the game. If everything appears to be working correctly, throw away the original.
You should now have only one save game (which is hereafter referred to as the original). Proceed as follows:
1. Make a duplicate of your save game (this is now the copy ).
2. Open the save game copy with the save game editor.
3. Change one variable, and save.
4. Compare the original and the copy of the save game. They should differ only by a few bytes. Note the offset and the variable which you changed.
5. Delete the save game copy and go back to step 1.
• The third method is the most difficult, but sometimes the fastest - decoding by inspection. If you have a good idea what some of the variables in your save game are, you can search the data and/or resource forks of the save game for these variables. For example, a string is particularly easy to find, since the characters are easily recognisable. Likewise, a series of 3 or more bytes has a high probability of being unique in the gave game, and should be easy to find.
You can also alter bytes in the data/resource fork to see what variables they correspond to in the game.
As well as finding the offset of the variable(s), we must also determine (guess) the type of variable used - how many bytes the variable spans, and whether it is signed or unsigned. Variable type are explained in more detail in Appendix A.
Strings are easy to identify, because you can see the individual characters in the save file. Look at the first character of a string - if the value of the preceding byte is exactly the same as the length of the string, it's probably a pascal string. If the string ends with one (or more) 0 bytes, it's probably a C string.
Most integer variables are signed because this is the 'default' state for variables in most development environments. Whether you correctly determine the signed state of a variable is not critical - you will only see a difference at high values.
Hint: A fractional variable is often stored as an integer by multiplying it by a common denominator (real fractional variables - floats - are very rare in save games).
To actually determine what type of integer variable is used, you will have to rely on a combination of knowledge of the game itself, and guesswork. If a variable value in the game ranges between, say 1 and 10, the variable type is probably byte (although it could be short or a nibble). If a variable can vary between 0 and 1000000, it's almost certainly stored as a long. You may be able to determine the variable type by inspection of the save game - if a integer is preceded by zero's, these may be part of the variable.
Example: In Bard's Tale, a character's experience can vary between 0 (it's starting value) and 'very large'. Inspecting the data fork of a character with 50 experience points (32 in hex), we see at the offset of the experience variable:
... 3A 00 00 00 32 ...
Since we know that the 3A is unrelated to the experience, it is a very good assumption that the three 0 bytes belong to the experience variable, and, therefore, that the variable type is a long.
You can also try changing a variable in the game to see what offsets are affected. However, even if only one byte has changed in the save game, it does not guarantee that the variable is stored in a single byte only. For example, the number 1000 would be stored as a two byte integer, but increasing it to 1001 would only change one byte, the low byte (and hence the offset read from this would be one byte too high). It is therefore good practice to change variables by a large amount (>255) if possible, as this will give you a better idea of what type of variable is used.
Compression and Encryption
Some save game files are compressed or encrypted. It is not possible to edit these save game files without knowledge of the compression or encryption algorithm. There is no easy way to tell if a file has been saved in this way. Often, you will find that there are no easily recognisable strings in the data/resource fork, even though the game saves strings such as names.
Example: The 'Exile' series of rpg's, and 'Worlds of Xeen' appear to use some form of compression or encryption.
It is also possible for a game to use a checksum to determine if the save game data has been edited. Again, it is not possible to edit such save games.
Example: 'Prince of Destruction' uses a checksum to determine if the save game data has been modified.
Simple vs Compound files
Some games (notably role-playing games, or RPG's) can save information about multiple characters (or players/pc's) in a single file. A file that contains multiple characters is referred to as a compound file (as opposed to a simple file which contains information about only one character).
Example: Bard's Tale saves each character in a separate file (a simple file). Ultima III saves all characters in a single file (a compound file).
In a compound file, each character in the data fork or in a resource is stored in a 'slot'. Each slot is the same size, but not every slot may be occupied. A file containing multiple resources of the same type can also be opened as a compound file. See the 'ACE Module Resources' section of "Development (part II)" for more information.
The Appearance manager
On MacOS 8 or higher, or on a system that has the appearance manager installed, ACE! will use the appearance manager for its dialogs, windows and controls. ACE modules contain extra resources that allow them to use the features of the appearance manager while preserving compatibility with non-appearance manager systems.
While testing a module, it can be useful to force ACE! to run in non-appearance manager mode. See the section on enabling startup options below. Note that:
1. On MacOS 8.0 or 8.1 systems, you should turn off the "System-wide platinum appearance" option in the "Appearance" control panel.
2. Some dialogs may still have gray backgrounds, and the initially selected edit text item in a dialog or window may be invisible. This occurs only when forcing ACE to run in non-appearance manager mode on systems with the appearance manager installed.
Startup options
Immediately after opening ACE, hold down the option key until the startup options dialog appears. The options are:
1. Debug mode: When debug mode is on, error messages contain information that can be useful when debugging a module.
2. Appearance manager: On systems that have the Appearance manager installed, you can force ACE to run in non-appearance manager mode. See the section 'The Appearance manager' above for more information.
3. Log errors: Error text and id's are written to a text file called "log" in the ACE application folder.
